package com.southminority.ethnic.service.organization;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.pojo.otherPojo.Organization;
import com.southminority.ethnic.controller.organization.vo.OrganizationVO;

import java.util.List;

/**
 * 机构组织服务接口.
 * <p>
 * 定义了机构组织模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 *
 * @author SouthMinority
 */
public interface OrganizationService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================

    /**
     * 获取所有在首页展示的机构列表（用于前端首页）。
     * <p>
     * 结果会根据 `homepage_order` 字段升序排列。
     *
     * @return {@link List<OrganizationVO>} 机构视图对象列表.
     */
    List<OrganizationVO> getHomepageOrganizationList();

    /**
     * 获取所有在团队页展示的机构列表（用于团队动态页）。
     * <p>
     * 仅返回启用状态且 `is_team_display=1` 的机构，默认按 `sort_order` 升序、`create_time` 降序。
     *
     * @return {@link List<OrganizationVO>} 机构视图对象列表.
     */
    List<OrganizationVO> getTeamDisplayOrganizationList();

    /**
     * 根据ID获取单个机构的详细信息（用于前端详情页）。
     * <p>
     * 此方法会增加机构的浏览次数.
     *
     * @param id 机构的唯一标识ID.
     * @return {@link OrganizationVO} 包含完整信息的机构视图对象.
     */
    OrganizationVO getOrganizationDetail(Long id);

    /**
     * 获取所有已启用的机构列表（用于前端列表页）。
     * <p>
     * 结果会根据 `sort_order` 字段升序排列。
     *
     * @return {@link List<OrganizationVO>} 机构视图对象列表.
     */
    List<OrganizationVO> getAllOrganizationList();


    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================

    /**
     * 分页查询机构列表（用于后台管理）。
     *
     * @param page             当前页码.
     * @param size             每页显示数量.
     * @param keyword          搜索关键词 (可选, 模糊匹配名称).
     * @param organizationType 机构类型 (可选, 精确匹配).
     * @param status           状态 (可选, 1-启用, 0-禁用).
     * @return {@link PageResult<OrganizationVO>} 封装了分页信息的查询结果.
     */
    PageResult<OrganizationVO> getOrganizationPageForAdmin(Integer page, Integer size, String keyword, String organizationType, Integer status);

    /**
     * 根据ID获取机构详情（用于后台管理编辑页）。
     *
     * @param id 机构的唯一标识ID.
     * @return {@link OrganizationVO} 包含完整信息的机构视图对象.
     */
    OrganizationVO getOrganizationDetailForAdmin(Long id);
    
    /**
     * 创建一个新的机构.
     *
     * @param organization 包含机构所有信息的POJO对象.
     * @return {@link OrganizationVO} 创建成功后返回的机构视图对象.
     */
    OrganizationVO createOrganization(Organization organization);

    /**
     * 更新一个已存在的机构.
     *
     * @param id           要更新的机构的ID.
     * @param organization 包含更新后信息的POJO对象.
     * @return {@link OrganizationVO} 更新成功后返回的机构视图对象.
     */
    OrganizationVO updateOrganization(Long id, Organization organization);

    /**
     * 根据ID删除一个机构（逻辑删除）。
     *
     * @param id 要删除的机构的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean deleteOrganization(Long id);

    /**
     * 批量删除机构（逻辑删除）。
     *
     * @param ids 包含多个要删除的机构ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean batchDeleteOrganizations(List<Long> ids);

    /**
     * 更新指定机构的状态.
     *
     * @param id     机构的ID.
     * @param status 新的状态值 (例如: 1-启用, 0-禁用).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean updateOrganizationStatus(Long id, Integer status);

    /**
     * 设置或取消机构的首页展示标识。
     *
     * @param id         机构ID
     * @param isFeatured 是否首页展示（1-是，0-否）
     * @return 操作成功返回true，否则false
     */
    boolean setOrganizationFeatured(Long id, Integer isFeatured);

    /**
     * 设置或取消机构的团队页展示标识。
     *
     * @param id      机构ID
     * @param display 是否团队展示（1-是，0-否）
     * @return 操作成功返回true，否则false
     */
    boolean setOrganizationTeamDisplay(Long id, Integer display);
}